// =============================================================================
//  STATS - Statistical Analysis Tools, v.0.01
//  Copyright (C) 2011  Marco Vettigli
// -----------------------------------------------------------------------------
//
// This program  is free software:  you can  redistribute it and/or  modify it
// under the terms of the  GNU General Public License as published by the Free
// Software Foundation,  either version 3 of the License,  or (at your option)
// any later version.
//
// This program is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY;  without even  the  implied  warranty  of  MERCHANTABILITY or
// FITNESS FOR A PARTICULAR PURPOSE.  See the  GNU General Public License  for
// more details.
//
// You  should  have received a copy of the  GNU General Public License  along
// with this program.  If not, see <http://www.gnu.org/licenses/>.
//
// =============================================================================
//
// SSTRINGS.H
// The class defines an array of ordered character elements with null value.
//
// Author: Marco Vettigli
//
// =============================================================================

#ifndef SSTRINGS_H
#define SSTRINGS_H

// == include directives =======================================================

#include <QVector>
#include <QString>
#include "sdoubles.h"

// == class definitions ========================================================

namespace StatS {

class SStrings
{

public:

// == constructors and destructors =============================================

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::SStrings(const QString)
    //
    // Default constructor for SStrings class object. Variable 'name' provide a
    // custom name to the array, else 'Untitled' name is given. SStrings object
    // cannot have a null name.
    //
    // -------------------------------------------------------------------------
    SStrings(const QString name = "Untitled");

// == getters ==================================================================

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::size()
    //
    // Returns number of elements currently stored in the array.
    //
    // -------------------------------------------------------------------------
    int size() const;

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::count()
    //
    // Returns number of not-null elements currently stored in the array.
    //
    // -------------------------------------------------------------------------
    int count() const;

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::name()
    //
    // Returns name of the array.
    //
    // -------------------------------------------------------------------------
    QString name() const;

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::get(int)
    //
    // Returns value of the element stored at position 'pos'. If null value is
    // present or 'pos' index is not valid, null QString is returned.
    //
    // -------------------------------------------------------------------------
    QString get(int pos) const;

// == setters ==================================================================

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::setName(const QString)
    //
    // The function changes the name of the array, given that 'name' provided
    // by used is valid. It returns true if changing was successful, false
    // else.
    //
    // -------------------------------------------------------------------------
    bool setName(const QString name);

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::assign(const QString, int)
    //
    // The function changes tha value of element at position indexed by 'pos'
    // starting from a character value 'val'. 'pos' index must be valid and val
    // can be null. The function returns true if assigment is successful,
    // else false.
    //
    // -------------------------------------------------------------------------
    bool assign(const QString val,
                int pos);

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::assign(double, int)
    //
    // The function changes tha value of element at position indexed by 'pos'
    // starting from a numeric value 'val'. If null numeric value is used (see
    // SDoubles definition), element is assigned to null character value. The
    // function returns true if assigment is successful, else false.
    //
    // -------------------------------------------------------------------------
    bool assign(double val,
                int pos);

// == inspectors ===============================================================

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::isNull(int)
    //
    // The function checks if element at 'pos' position is null. It returns
    // false also if 'pos' index is not valid.
    //
    // -------------------------------------------------------------------------
    bool isNull(int pos) const;

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::isIndex(int)
    //
    // The function checks if 'pos' number is valid as index for pointing an
    // element of the array.
    //
    // -------------------------------------------------------------------------
    bool isIndex(int pos) const;

// == accessor function declarations ===========================================

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::append(const QString, int)
    //
    // The function appends a given number 'num' of elements with value given
    // by character value 'val'. Integer 'num' must be positive. The function
    // returns true if the appending is successful, else false.
    //
    // -------------------------------------------------------------------------
    bool append(const QString val = null,
                int num = 1);

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::append(double, int)
    //
    // The function appends a given number 'num' of elements with value given
    // by numeric value 'val'. Integer 'num' must be positive. If 'val' is null
    // (see SDoubles definition), null character values are appended. The
    // function returns true if the appending is successful, else false.
    //
    // -------------------------------------------------------------------------
    bool append(double val,
                int num = 1);

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::insert(const QString, int, int)
    //
    // The function inserts at 'pos' position a given number 'num' of elements
    // with value provided by character value 'val'. Integer 'num' must be
    // positive and 'pos' index valid. The function returns true if the
    // insertion is successful, else false.
    //
    // -------------------------------------------------------------------------
    bool insert(const QString val,
                int pos = 0,
                int num = 1);

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::insert(double, int, int)
    //
    // The function inserts at 'pos' position a given number 'num' of elements
    // with value provided by numeric value 'val'. Integer 'num' must be
    // positive and 'pos' index valid. If 'val' is null (see SDoubles
    // definition), null character values are inserted. The function returns
    // true if the insertion is successful, else false.
    //
    // -------------------------------------------------------------------------
    bool insert(double val,
                int pos = 0,
                int num = 1);

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::remove(int, int)
    //
    // The function removes a number 'num' of element from position 'pos' of
    // the array. The deletion cannot overflow the array size. It returns
    // true is deletion is successful, else false.
    //
    // -------------------------------------------------------------------------
    bool remove(int pos,
                int num = 1);

    // -- public ---------------------------------------------------------------
    // StatS::SStrings::debug()
    //
    // Returns a QString representation of the array.
    //
    // -------------------------------------------------------------------------
    QString debug() const;

// == variable declarations ====================================================

    static const QString null;      // null character value

private:

    QVector<QString>* _data;         // storage of elemets
    QString _name;                   // name of the array

// == private function declarations ============================================

};

}

#endif // SSTRINGS_H
